---
title: ServerOptions 配置
description: Feat HTTP 服务器配置选项指南
sidebar:
    order: 2
---

# ServerOptions 配置详解

Feat HTTP 服务器配置类，用于配置服务器的各项参数，包括基础配置、性能调优、安全设置和调试功能等。

## 基础配置

### bannerEnabled
**类型:** `boolean` **默认值:** `true`

是否在启动时显示 Feat HTTP 服务器的版本信息。

```java
options.bannerEnabled(false);
```

**使用场景：** 生产环境隐藏版本信息、保持控制台输出简洁

### idleTimeout
**类型:** `long` **默认值:** `60000`（毫秒）

设置连接闲置超时时间。当客户端连接在指定时间内没有数据交互时，服务器将关闭该连接。

```java
options.setIdleTimeout(120000); // 2分钟
```

**使用场景：** 防止空闲连接占用资源、优化连接管理、长连接超时控制

### shutdownHook
**类型:** `Runnable` **默认值:** `null`

设置服务器关闭钩子。当服务器关闭时，会执行该钩子函数。

```java
options.shutdownHook(() -> {
    System.out.println("服务器关闭，执行资源清理...");
    // 执行资源清理、状态保存等操作
});
```

**使用场景：** 资源清理、状态保存、关闭通知、优雅停机

## 性能调优

### threadNum
**类型:** `int` **默认值:** `Math.max(Runtime.getRuntime().availableProcessors(), 2)`

设置 HTTP 服务器的工作线程数。

```java
options.threadNum(8);
```

**最佳实践：**
- IO 密集型应用：CPU 核数的 2-4 倍
- CPU 密集型应用：CPU 核数的 1-2 倍

### readBufferSize
**类型:** `int` **默认值:** `8 * 1024`（8KB）

设置读缓冲区大小。用于存储客户端发送的 HTTP 请求数据。

```java
options.readBufferSize(16 * 1024); // 16KB
```

**最佳实践：** 缓冲区至少要能容纳一个完整的 URL 或 Header 值，文件上传场景适当增加

### writeBufferSize
**类型:** `int` **默认值:** `8 * 1024`（8KB）

设置写缓冲区大小。用于存储发送给客户端的 HTTP 响应数据。

```java
options.writeBufferSize(16 * 1024); // 16KB
```

**最佳实践：** 响应大文件时适当增加，注意内存资源平衡

### lowMemory
**类型:** `boolean` **默认值:** `false`

是否启用低内存模式。在资源受限环境中可减少内存占用。

```java
options.setLowMemory(true);
```

**使用场景：** 嵌入式设备、容器化部署、资源受限环境

### group
**类型:** `AsynchronousChannelGroup` **默认值:** `null`

设置异步通道组，用于管理异步 IO 操作的线程组。

```java
AsynchronousChannelGroup channelGroup = AsynchronousChannelGroup.withFixedThreadPool(
    4, Executors.defaultThreadFactory());
    
options.group(channelGroup);
```

**使用场景：** 自定义异步 IO 线程池、多服务共享线程池资源

## 安全设置

### maxRequestSize
**类型:** `long` **默认值:** `Integer.MAX_VALUE`

设置允许的最大请求报文大小。防止恶意大请求攻击。

```java
options.setMaxRequestSize(10 * 1024 * 1024); // 10MB
```

**最佳实践：** 根据业务需求设置合理限制，文件上传场景适当调大

### headerLimiter
**类型:** `int` **默认值:** `100`

设置请求头的最大数量限制。超过此限制的请求头将被忽略。

```java
options.headerLimiter(50);
```

**使用场景：** 防止 HTTP 头部攻击、限制异常请求、保护服务器资源

### secure
**类型:** `boolean` **默认值:** `false`

是否启用加密通信（HTTPS）。添加 SslPlugin 插件时自动设置为 true。

```java
// 添加 SSL 插件后，secure 会自动设置为 true
options.addPlugin(new SslPlugin<>("keystore.jks", "password", "JKS"));
```

**使用场景：** 保护敏感数据传输、提高服务安全性、满足合规要求

### proxyProtocolSupport
**类型:** `方法`

启用代理协议支持。当服务器部署在代理后面时，可获取客户端真实 IP。

```java
options.proxyProtocolSupport();
```

**使用场景：** 负载均衡环境、获取客户端真实 IP、与代理服务器集成

## 调试功能

### debug
**类型:** `boolean` **默认值:** `false`

是否开启调试模式。开启后会打印请求和响应的详细信息。

```java
options.debug(true);
```

**使用场景：** 开发环境调试、排查通信问题、分析请求处理流程

**注意：** 生产环境必须关闭，避免性能下降和信息泄露

## 插件系统

### addPlugin
**类型:** `方法`

添加服务器插件。扩展服务器功能，如 SSL 支持、代理协议支持、流量监控等。

```java
// 添加单个插件
options.addPlugin(new SslPlugin<>("keystore.jks", "password", "JKS"));
    
// 批量添加插件
List<Plugin<HttpEndpoint>> pluginList = new ArrayList<>();
pluginList.add(new SslPlugin<>("keystore.jks", "password", "JKS"));
pluginList.add(new CustomPlugin<>());
options.addPlugin(pluginList);
```

**常用插件：** SslPlugin（HTTPS）、ProxyProtocolPlugin（代理协议）、StreamMonitorPlugin（流量监控）

## 配置示例

### 开发环境配置

```java
Feat.httpServer(options -> {
    // 基础配置
    options.serverName("dev-app-v1.0");
    options.bannerEnabled(true);
    options.setIdleTimeout(300000); // 5分钟
    
    // 性能调优
    options.threadNum(Runtime.getRuntime().availableProcessors() * 2);
    options.readBufferSize(16 * 1024);
    options.writeBufferSize(16 * 1024);
    
    // 安全设置
    options.setMaxRequestSize(50 * 1024 * 1024); // 50MB
    options.headerLimiter(100);
    
    // 调试功能
    options.debug(true); // 开发环境启用调试
})
.listen(8080);
```

### 生产环境配置

```java
Feat.httpServer(options -> {
    // 基础配置
    options.serverName("prod-app"); // 隐藏版本信息
    options.bannerEnabled(false); // 关闭 banner
    options.setIdleTimeout(60000); // 1分钟
    
    // 性能调优
    options.threadNum(Runtime.getRuntime().availableProcessors() * 2);
    options.readBufferSize(8 * 1024);
    options.writeBufferSize(8 * 1024);
    
    // 安全设置
    options.setMaxRequestSize(10 * 1024 * 1024); // 10MB
    options.headerLimiter(50);
    options.addPlugin(new SslPlugin<>("/path/to/keystore.jks", "password", "JKS"));
    options.proxyProtocolSupport();
    
    // 调试功能
    options.debug(false); // 禁用调试
})
.listen(443);
```

## 最佳实践

### 性能优化
- 根据应用特性和硬件资源合理设置线程数
- 通过压测确定最优缓冲区大小
- 生产环境关闭调试功能
- 容器环境适当降低线程数和缓冲区大小

### 安全防护
- 设置合理的请求大小限制和请求头数量限制
- 修改默认服务器名称，避免暴露版本信息
- 生产环境禁用 banner 显示
- 敏感数据传输启用 HTTPS

### 环境差异化配置
- 开发环境：启用调试功能，放宽资源限制
- 测试环境：模拟生产配置，进行性能测试
- 生产环境：关闭调试功能，加强安全限制